Add plans 87 and 88: GitHub Alerts and TOC directive rules - #139
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #139 +/- ##
=======================================
Coverage 86.25% 86.25%
=======================================
Files 92 92
Lines 9880 9880
=======================================
Hits 8522 8522
Misses 886 886
Partials 472 472 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
Adds two new roadmap plan documents for upcoming mdsmith lint rules (GitHub Alerts flavor validation and TOC-directive detection), and updates the plans index in PLAN.md so they appear in the generated plans table.
Changes:
- Added plan 87 describing an MDS034 extension to detect/fix GitHub Alerts markers in non-GFM target flavors.
- Added plan 88 describing a new opt-in MDS035 rule to detect renderer-specific TOC directives.
- Updated
PLAN.mdcatalog output to include plans 87 and 88.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| plan/87_markdown-flavor-github-alerts.md | New plan documenting detection/fix behavior to extend flavor validation for GitHub Alerts syntax. |
| plan/88_toc-directive-migration.md | New plan for an opt-in rule to flag renderer-specific TOC directives and guide migration. |
| PLAN.md | Updates the generated plans catalog table to include the two new plans. |
Plan 87 extends MDS034 (flavor validation, plan 86) with a 13th
feature: GitHub Alerts `> [!NOTE]` blockquotes. Detected via AST
walk on the dual parser, no new goldmark extension needed. Fix
strips the marker line while preserving the blockquote body.
Plan 88 adds a new rule MDS035 that flags four renderer-specific
TOC directives (`[TOC]`, `[[_TOC_]]`, `[[toc]]`, `${toc}`) which
silently disappear on CommonMark / goldmark, and suggests the
existing `<?catalog?>` directive as a portable replacement.
These address the high-value items from the markdown-extension
survey comment. Items evaluated and deliberately skipped:
- Spoilers `||text||`: only Discord/Mattermost, severe ambiguity
with table pipes, no linter in the ecosystem covers it.
- Generic attribute syntax beyond heading IDs: plan 86 already
enables `parser.WithAttribute()`; heading IDs are feature 8.
- Pandoc `:::` fenced divs / MyST / MkDocs admonitions: five
mutually incompatible variants, no standardization, goldmark
renders them as plain paragraphs (not a lint-visible failure).
Address Copilot review: - catalog replacement mismatch: <?catalog?> is a file-index generator (needs glob + frontmatter), not an in-document heading TOC generator. Add a comparison table, explain that <?catalog?> is the right replacement only for index-page uses of [[_TOC_]]/[TOC], and note mdsmith has no built-in heading TOC generator for the more common in-document case. - Error message: combine into a single fenced code block (no longer split across two inline spans) and name both CommonMark and goldmark as failure renderers.
2937389 to
c878ad9
Compare
Address Copilot review: - Error message: drop trailing period and capital leading 'For', matching the mdsmith CLAUDE.md convention (lowercase, no trailing punctuation). New message keeps both pointers — the missing heading-TOC generator and MDS019 for file indexes. - Detection: `[TOC]` is a valid CommonMark shortcut reference link. The earlier design would false-positive when a matching `[TOC]: <url>` definition is present. Add an explicit link-reference map lookup (case-insensitive label) before emitting the diagnostic for this pattern; the other three patterns keep their simple regex match. - Tasks: add a step for the link-reference suppression and a good fixture exercising it.
Address Copilot review: - Failure description: earlier text said the directives "simply disappear from the rendered output" / render as "empty text". That was wrong — goldmark and CommonMark render the literal directive token (`[TOC]`, `[[_TOC_]]`, etc.) as paragraph text. Rewrite the Context section to describe the actual behavior: a visible failure where the author's intent is lost but the token itself is shown. Update the front-matter summary and Goal paragraph to match. - Error message: the previous version started with `[TOC]`, which read as a capitalized leading token and conflicted with the note claiming a "Lowercase start". Reword to start with the lowercase word "unsupported": `unsupported TOC directive \`[TOC]\`; mdsmith has no heading TOC equivalent; use <?catalog?> for file indexes (MDS019)`. The backticked directive token is quotation, not prose capitalization. Also addresses a Copilot comment on PLAN.md: the catalog table rows for plans 87 and 88 were added by running `mdsmith fix PLAN.md`, not edited by hand. Re-running `mdsmith fix PLAN.md` after this change produces no diff, confirming the table is in sync with the plan files.
Copilot review noted the error message backticked `[TOC]` but left `<?catalog?>` as bare text, inconsistent with the following explanation that says directive tokens are backticked. Add backticks around `<?catalog?>` and update the explanation to cover both tokens. Two other comments in the same review batch — claiming the comparison tables in plans 87 and 88 start each row with `||` and have an empty leading column — are factually incorrect. Both tables use a single leading `|`; replies posted on the threads with the verbatim current content.
Copilot review: the example error message hardcoded [TOC],
which would misrepresent the diagnostic for the other three
patterns ([[_TOC_]], [[toc]], ${toc}).
Change: describe the message as templated on `{directive}` and
show the concrete message each of the four patterns would emit.
The template itself is unchanged; only the documentation makes
clear that the matched token is substituted per call site.
Also explicitly document the mdsmith error-message convention
(lowercase start, no trailing punctuation) inline so that
implementation follows it for every pattern.
Address two Copilot review points: - plan 87: described the non-GFM render of `> [!NOTE]` as a "silent failure", but the literal marker text is visibly rendered — that is a visible failure. Reword to match. - plan 88: the phrase "None are part of CommonMark, GFM, or goldmark" was ambiguous — `[TOC]` IS valid CommonMark syntax as a shortcut reference link. Reword to make clear that none of the four tokens are standardized as TOC directives, while `[TOC]` remains a valid (but differently-resolved) link shorthand.
|
🟢 Merge Queue — picked up This PR is in the queue and will be batched with other Next: No action needed — you'll get another comment when CI starts on the batch. View merge queue run. |
|
🔵 Merge Queue — CI running Merged into batch branch Next: No action needed — you'll be notified when CI completes. |
|
✅ Merge Queue — merged This PR landed on Next: Done — nothing more to do here. |
Summary
This PR adds two new planning documents that outline upcoming linting rules for mdsmith, and bumps the merge-queue-action to v0.5.0:
jeduden/merge-queue-actionfrom v0.4.1 → v0.5.0Changes
plan/87_markdown-flavor-github-alerts.md (new)
> [!NOTE]blockquote prefix)plan/88_toc-directive-migration.md (new)
[TOC],[[_TOC_]],[[toc]],${toc}<?catalog?>directive for the file-index use case; calls out that heading-TOCs have no mdsmith equivalent[TOC]PLAN.md (regenerated)
mdsmith fix PLAN.mdexpanded the catalog directive to include plans 87 and 88.github/workflows/merge-queue.yml (workflow bump)
jeduden/merge-queue-actionfromv0.4.1(10aad589) tov0.5.0(fd94568d)Implementation Notes
Both plans follow the established pattern from plan 86 (flavor validation framework):
https://claude.ai/code/session_018Y66EF7D9E8kC3mwTh9E2m